<HTML>
<BODY>
<PRE>
<!-- Manpage converted by man2html 3.0.1 -->


<B><A HREF="REGEX.html">REGEX(3)</A></B>						 <B><A HREF="REGEX.html">REGEX(3)</A></B>


</PRE>
<H2>NAME</H2><PRE>
       regcomp,  regexec,  regerror, regfree - regular-expression
       library


</PRE>
<H2>SYNOPSIS</H2><PRE>
       <B>#include</B> <B>&lt;sys/types.h&gt;</B>
       <B>#include</B> <B>&lt;regex.h&gt;</B>

       int	regcomp(regex_t *preg,	     const char *pattern,
		 int cflags);

       int regexec(const regex_t *preg,       const char *string,
		 size_t nmatch, regmatch_t pmatch[], int eflags);

       size_t regerror(int errcode,	     const regex_t *preg,
		 char *errbuf, size_t errbuf_size);

       void regfree(regex_t *preg);


</PRE>
<H2>DESCRIPTION</H2><PRE>
       These routines implement POSIX 1003.2 regular  expressions
       (``RE''s); see <B><A HREF="re_format.html">re_format(7)</A></B><I>.</I>  <I>Regcomp</I> compiles an RE writ-
       ten as a string into an	internal  form,  <I>regexec</I>  matches
       that  internal  form against a string and reports results,
       <I>regerror</I> transforms error codes from  either  into  human-
       readable messages, and <I>regfree</I> frees any dynamically-allo-
       cated storage used by the internal form of an RE.

       The header <I>&lt;regex.h&gt;</I> declares two structure types, <I>regex</I><B>_</B><I>t</I>
       and <I>regmatch</I><B>_</B><I>t</I>, the former for compiled internal forms and
       the latter for match reporting.	It also declares the four
       functions, a type <I>regoff</I><B>_</B><I>t</I>, and a number of constants with
       names starting with ``REG_''.

       <I>Regcomp</I> compiles the regular expression contained  in  the
       <I>pattern</I> string, subject to the flags in <I>cflags</I>, and places
       the results in the <I>regex</I><B>_</B><I>t</I> structure pointed to	by  <I>preg</I>.
       <I>Cflags</I>  is the bitwise OR of zero or more of the following
       flags:

       REG_EXTENDED  Compile modern  (``extended'')  REs,  rather
		     than  the	obsolete (``basic'') REs that are
		     the default.

       REG_BASIC     This is a synonym for 0, provided as a coun-
		     terpart to REG_EXTENDED to improve readabil-
		     ity.

       REG_NOSPEC    Compile  with  recognition  of  all  special
		     characters  turned  off.  All characters are
		     thus considered ordinary, so the ``RE'' is a
		     literal  string.  This is an extension, com-
		     patible with  but	not  specified	by  POSIX
		     1003.2,  and  should be used with caution in

			  March 20, 1994			1

<B><A HREF="REGEX.html">REGEX(3)</A></B>						 <B><A HREF="REGEX.html">REGEX(3)</A></B>

		     software intended to be  portable	to  other
		     systems.	REG_EXTENDED  and  REG_NOSPEC may
		     not be used in the same call to <I>regcomp</I>.

       REG_ICASE     Compile   for    matching	  that	  ignores
		     upper/lower  case distinctions.  See <I>re</I><B>_</B><I>for-</I>
		     <B><A HREF="mat.html">mat(7)</A></B><I>.</I>

       REG_NOSUB     Compile for matching that need  only  report
		     success or failure, not what was matched.

       REG_NEWLINE   Compile  for newline-sensitive matching.  By
		     default, newline is  a  completely  ordinary
		     character	with no special meaning in either
		     REs  or  strings.	 With  this  flag,   `[^'
		     bracket expressions and `.' never match new-
		     line, a `^' anchor matches the  null  string
		     after  any newline in the string in addition
		     to its normal function, and the  `$'  anchor
		     matches  the  null string before any newline
		     in the string  in	addition  to  its  normal
		     function.

       REG_PEND      The  regular  expression  ends,  not  at the
		     first NUL, but  just  before  the	character
		     pointed  to  by  the  <I>re</I><B>_</B><I>endp</I>  member of the
		     structure pointed to by <I>preg</I>.   The  <I>re</I><B>_</B><I>endp</I>
		     member  is  of type <I>const</I> <I>char</I> <I>*</I>.	This flag
		     permits inclusion of NULs in  the	RE;  they
		     are considered ordinary characters.  This is
		     an extension, compatible with but not speci-
		     fied  by  POSIX  1003.2,  and should be used
		     with caution  in  software  intended  to  be
		     portable to other systems.

       When successful, <I>regcomp</I> returns 0 and fills in the struc-
       ture pointed to by <I>preg</I>.  One  member  of  that	structure
       (other  than  <I>re</I><B>_</B><I>endp</I>)  is  publicized:	<I>re</I><B>_</B><I>nsub</I>,  of type
       <I>size</I><B>_</B><I>t</I>, contains the number  of	parenthesized  subexpres-
       sions  within the RE (except that the value of this member
       is undefined if the REG_NOSUB flag was used).  If  <I>regcomp</I>
       fails,  it returns a non-zero error code; see DIAGNOSTICS.

       <I>Regexec</I> matches the compiled RE pointed to by <I>preg</I> against
       the  <I>string</I>,  subject  to the flags in <I>eflags</I>, and reports
       results using <I>nmatch</I>, <I>pmatch</I>, and the returned value.  The
       RE  must  have  been  compiled by a previous invocation of
       <I>regcomp</I>.  The compiled form is not altered  during  execu-
       tion  of  <I>regexec</I>,  so  a  single  compiled RE can be used
       simultaneously by multiple threads.

       By default, the NUL-terminated string pointed to by <I>string</I>
       is  considered to be the text of an entire line, minus any
       terminating newline.  The <I>eflags</I> argument is  the  bitwise

			  March 20, 1994			2

<B><A HREF="REGEX.html">REGEX(3)</A></B>						 <B><A HREF="REGEX.html">REGEX(3)</A></B>

       OR of zero or more of the following flags:

       REG_NOTBOL    The first character of the string is not the
		     beginning of  a  line,  so  the  `^'  anchor
		     should  not  match before it.  This does not
		     affect  the  behavior  of	 newlines   under
		     REG_NEWLINE.

       REG_NOTEOL    The  NUL terminating the string does not end
		     a line, so the `$' anchor should  not  match
		     before  it.  This does not affect the behav-
		     ior of newlines under REG_NEWLINE.

       REG_STARTEND  The  string  is  considered  to   start   at
		     <I>string</I> +  <I>pmatch</I>[0].<I>rm</I><B>_</B><I>so</I> and to have a ter-
		     minating	 NUL	located    at	 <I>string</I> +
		     <I>pmatch</I>[0].<I>rm</I><B>_</B><I>eo</I>  (there need not actually be
		     a NUL at that location), regardless  of  the
		     value  of <I>nmatch</I>.	See below for the defini-
		     tion of  <I>pmatch</I>  and  <I>nmatch</I>.   This  is  an
		     extension, compatible with but not specified
		     by POSIX 1003.2, and  should  be  used  with
		     caution  in software intended to be portable
		     to other  systems.   Note	that  a  non-zero
		     <I>rm</I><B>_</B><I>so</I>  does  not imply REG_NOTBOL; REG_STAR-
		     TEND  affects  only  the  location  of   the
		     string, not how it is matched.

       See  <B><A HREF="re_format.html">re_format(7)</A></B>  for  a discussion of what is matched in
       situations where an RE or a portion  thereof  could  match
       any of several substrings of <I>string</I>.

       Normally,  <I>regexec</I>  returns 0 for success and the non-zero
       code REG_NOMATCH for failure.  Other non-zero error  codes
       may  be	returned  in exceptional situations; see DIAGNOS-
       TICS.

       If REG_NOSUB was specified in the compilation of  the  RE,
       or  if  <I>nmatch</I>  is  0, <I>regexec</I> ignores the <I>pmatch</I> argument
       (but see below for the case where REG_STARTEND  is  speci-
       fied).	Otherwise,  <I>pmatch</I>  points  to an array of <I>nmatch</I>
       structures of type <I>regmatch</I><B>_</B><I>t</I>.  Such a  structure  has  at
       least  the  members <I>rm</I><B>_</B><I>so</I> and <I>rm</I><B>_</B><I>eo</I>, both of type <I>regoff</I><B>_</B><I>t</I>
       (a signed arithmetic type at least as large  as	an  <I>off</I><B>_</B><I>t</I>
       and  a <I>ssize</I><B>_</B><I>t</I>), containing respectively the offset of the
       first character of a substring and the offset of the first
       character  after  the  end  of the substring.  Offsets are
       measured from the beginning of the <I>string</I>  argument  given
       to  <I>regexec</I>.   An empty substring is denoted by equal off-
       sets, both indicating the character  following  the  empty
       substring.

       The  0th  member of the <I>pmatch</I> array is filled in to indi-
       cate what substring of <I>string</I> was matched  by  the  entire

			  March 20, 1994			3

<B><A HREF="REGEX.html">REGEX(3)</A></B>						 <B><A HREF="REGEX.html">REGEX(3)</A></B>

       RE.   Remaining	members report what substring was matched
       by parenthesized subexpressions within the  RE;	member	<I>i</I>
       reports	 subexpression	<I>i</I>,  with  subexpressions  counted
       (starting at 1) by the order of their opening  parentheses
       in  the	RE, left to right.  Unused entries in the array--
       corresponding either to subexpressions that did	not  par-
       ticipate in the match at all, or to subexpressions that do
       not exist in the RE  (that  is,	<I>i</I> &gt;  <I>preg</I>-&gt;<I>re</I><B>_</B><I>nsub</I>)--have
       both  <I>rm</I><B>_</B><I>so</I>  and <I>rm</I><B>_</B><I>eo</I> set to -1.  If a subexpression par-
       ticipated in the match several times,  the  reported  sub-
       string  is  the last one it matched.  (Note, as an example
       in particular, that when the RE `(b*)+' matches `bbb', the
       parenthesized subexpression matches each of the three `b's
       and then an infinite number of empty strings following the
       last  `b',  so  the  reported substring is one of the emp-
       ties.)

       If REG_STARTEND is specified,  <I>pmatch</I>  must  point  to  at
       least one <I>regmatch</I><B>_</B><I>t</I> (even if <I>nmatch</I> is 0 or REG_NOSUB was
       specified), to hold the input  offsets  for  REG_STARTEND.
       Use  for output is still entirely controlled by <I>nmatch</I>; if
       <I>nmatch</I> is 0 or  REG_NOSUB  was  specified,  the	value  of
       <I>pmatch</I>[0] will not be changed by a successful <I>regexec</I>.

       <I>Regerror</I>  maps  a  non-zero <I>errcode</I> from either <I>regcomp</I> or
       <I>regexec</I> to a human-readable, printable message.	 If  <I>preg</I>
       is non-NULL, the error code should have arisen from use of
       the <I>regex</I><B>_</B><I>t</I> pointed to by <I>preg</I>, and if the error code came
       from <I>regcomp</I>, it should have been the result from the most
       recent <I>regcomp</I> using that <I>regex</I><B>_</B><I>t</I>.  (<I>Regerror</I> may be  able
       to  supply  a more detailed message using information from
       the <I>regex</I><B>_</B><I>t</I>.)  <I>Regerror</I> places the NUL-terminated  message
       into  the buffer pointed to by <I>errbuf</I>, limiting the length
       (including the NUL) to at most <I>errbuf</I><B>_</B><I>size</I> bytes.  If  the
       whole  message won't fit, as much of it as will fit before
       the  terminating  NUL  is  supplied.   In  any  case,  the
       returned  value	is  the size of buffer needed to hold the
       whole message (including terminating NUL).  If <I>errbuf</I><B>_</B><I>size</I>
       is 0, <I>errbuf</I> is ignored but the return value is still cor-
       rect.

       If the <I>errcode</I>  given  to  <I>regerror</I>  is	first  ORed  with
       REG_ITOA,  the  ``message''  that results is the printable
       name of the error code, e.g. ``REG_NOMATCH'', rather  than
       an explanation thereof.	If <I>errcode</I> is REG_ATOI, then <I>preg</I>
       shall be non-NULL and the <I>re</I><B>_</B><I>endp</I> member of the	structure
       it  points to must point to the printable name of an error
       code; in this case, the result in <I>errbuf</I>  is  the  decimal
       digits  of  the	numeric value of the error code (0 if the
       name  is  not  recognized).   REG_ITOA  and  REG_ATOI  are
       intended  primarily  as	debugging  facilities;	they  are
       extensions, compatible with but	not  specified	by  POSIX
       1003.2,	and  should  be  used  with  caution  in software
       intended to be portable to other systems.  Be warned  also

			  March 20, 1994			4

<B><A HREF="REGEX.html">REGEX(3)</A></B>						 <B><A HREF="REGEX.html">REGEX(3)</A></B>

       that they are considered experimental and changes are pos-
       sible.

       <I>Regfree</I> frees any dynamically-allocated storage associated
       with  the  compiled  RE pointed to by <I>preg</I>.  The remaining
       <I>regex</I><B>_</B><I>t</I> is no longer a valid compiled RE and the effect of
       supplying it to <I>regexec</I> or <I>regerror</I> is undefined.

       None of these functions references global variables except
       for tables of constants; all are safe for use from  multi-
       ple threads if the arguments are safe.


</PRE>
<H2>IMPLEMENTATION CHOICES</H2><PRE>
       There  are  a number of decisions that 1003.2 leaves up to
       the implementor, either by explicitly saying ``undefined''
       or  by  virtue  of them being forbidden by the RE grammar.
       This implementation treats them as follows.

       See <B><A HREF="re_format.html">re_format(7)</A></B> for a discussion  of  the  definition  of
       case-independent matching.

       There  is no particular limit on the length of REs, except
       insofar as memory is limited.  Memory  usage  is  approxi-
       mately  linear  in  RE size, and largely insensitive to RE
       complexity, except for bounded repetitions.  See BUGS  for
       one  short  RE  using them that will run almost any system
       out of memory.

       A backslashed character other than one specifically  given
       a  magic meaning by 1003.2 (such magic meanings occur only
       in obsolete [``basic''] REs) is taken as an ordinary char-
       acter.

       Any unmatched [ is a REG_EBRACK error.

       Equivalence classes cannot begin or end bracket-expression
       ranges.	The endpoint of one range cannot begin another.

       RE_DUP_MAX, the limit on repetition counts in bounded rep-
       etitions, is 255.

       A  repetition  operator (?, *, +, or bounds) cannot follow
       another repetition operator.  A repetition operator cannot
       begin an expression or subexpression or follow `^' or `|'.

       `|' cannot appear first or last in  a  (sub)expression  or
       after  another  `|',  i.e.  an operand of `|' cannot be an
       empty subexpression.  An  empty	parenthesized  subexpres-
       sion, `()', is legal and matches an empty (sub)string.  An
       empty string is not a legal RE.

       A `{' followed by a digit is considered the  beginning  of
       bounds  for  a  bounded repetition, which must then follow
       the syntax for bounds.  A `{' <I>not</I> followed by a	digit  is

			  March 20, 1994			5

<B><A HREF="REGEX.html">REGEX(3)</A></B>						 <B><A HREF="REGEX.html">REGEX(3)</A></B>

       considered an ordinary character.

       `^'  and  `$' beginning and ending subexpressions in obso-
       lete (``basic'') REs are anchors, not ordinary characters.


</PRE>
<H2>SEE ALSO</H2><PRE>
       <B><A HREF="grep.html">grep(1)</A></B>, <B><A HREF="re_format.html">re_format(7)</A></B>

       POSIX  1003.2,  sections 2.8 (Regular Expression Notation)
       and B.5 (C Binding for Regular Expression Matching).


</PRE>
<H2>DIAGNOSTICS</H2><PRE>
       Non-zero error codes from <I>regcomp</I> and <I>regexec</I> include  the
       following:

       REG_NOMATCH    regexec() failed to match
       REG_BADPAT     invalid regular expression
       REG_ECOLLATE   invalid collating element
       REG_ECTYPE     invalid character class
       REG_EESCAPE    \ applied to unescapable character
       REG_ESUBREG    invalid backreference number
       REG_EBRACK     brackets [ ] not balanced
       REG_EPAREN     parentheses ( ) not balanced
       REG_EBRACE     braces { } not balanced
       REG_BADBR      invalid repetition count(s) in { }
       REG_ERANGE     invalid character range in [ ]
       REG_ESPACE     ran out of memory
       REG_BADRPT     ?, *, or + operand invalid
       REG_EMPTY      empty (sub)expression
       REG_ASSERT     ``can't happen''--you found a bug
       REG_INVARG     invalid argument, e.g. negative-length string


</PRE>
<H2>HISTORY</H2><PRE>
       Originally  written  by Henry Spencer.  Altered for inclu-
       sion in the distribution.


</PRE>
<H2>BUGS</H2><PRE>
       This is an  alpha  release  with  known	defects.   Please
       report problems.

       There  is one known functionality bug.  The implementation
       of  internationalization  is  incomplete:  the  locale  is
       always  assumed	to be the default one of 1003.2, and only
       the collating elements etc. of that locale are  available.

       The  back-reference code is subtle and doubts linger about
       its correctness in complex cases.

       <I>Regexec</I> performance is poor.  This will improve with later
       releases.  <I>Nmatch</I> exceeding 0 is expensive; <I>nmatch</I> exceed-
       ing 1 is worse.	<I>Regexec</I> is largely insensitive to RE com-
       plexity	<I>except</I>	that back references are massively expen-
       sive.  RE length does matter; in particular,  there  is	a
       strong  speed  bonus  for keeping RE length under about 30

			  March 20, 1994			6

<B><A HREF="REGEX.html">REGEX(3)</A></B>						 <B><A HREF="REGEX.html">REGEX(3)</A></B>

       characters, with most special characters counting  roughly
       double.

       <I>Regcomp</I> implements bounded repetitions by macro expansion,
       which is costly in time and space if counts are	large  or
       bounded	 repetitions   are  nested.   An  RE  like,  say,
       `((((a{1,100}){1,100}){1,100}){1,100}){1,100}' will (even-
       tually) run almost any existing machine out of swap space.

       There are suspected  problems  with  response  to  obscure
       error  conditions.   Notably,  certain  kinds  of internal
       overflow, produced only by truly enormous REs or by multi-
       ply  nested  bounded repetitions, are probably not handled
       well.

       Due to a mistake in 1003.2, things like	`a)b'  are  legal
       REs  because  `)' is a special character only in the pres-
       ence of a previous unmatched `('.   This  can't	be  fixed
       until the spec is fixed.

       The  standard's	definition  of	back references is vague.
       For example, does `a\(\(b\)*\2\)*d' match `abbbd'?   Until
       the  standard  is clarified, behavior in such cases should
       not be relied on.

       The implementation of word-boundary matching is a bit of a
       kludge, and bugs may lurk in combinations of word-boundary
       matching and anchoring.

			  March 20, 1994			7

</PRE>
<HR>
<ADDRESS>
Man(1) output converted with
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
</ADDRESS>
</BODY>
</HTML>
